Codecov Report

❌ Patch coverage is 7.14286% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 44.61%. Comparing base (b04ec2e) to head (2ee43b9).

@@            Coverage Diff             @@
##             main      #46      +/-   ##
==========================================
- Coverage   45.49%   44.61%   -0.89%     
==========================================
  Files           4        4              
  Lines         455      464       +9     
==========================================
  Hits          207      207              
- Misses        248      257       +9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@copilot Without writing any new code, can you suggest a few approaches to making this package basically work for mmaped files on linux, understanding that syscall tracing is not the way here.

@copilot Without writing any new code, can you suggest a few approaches to making this package basically work for mmaped files on linux, understanding that syscall tracing is not the way here.

Here are several approaches to support mmap'd files on Linux without syscall tracing:

1. eBPF-based tracing (most accurate)

• Use BCC/bpftrace to trace page faults (e.g., page_fault_user tracepoint)
• Track memory-mapped regions via mmap/munmap tracepoints
• Calculate actual bytes accessed from page fault counts
• Pros: Accurate, minimal overhead
• Cons: Requires kernel >=4.7, root or CAP_BPF, additional dependencies (bcc-tools)

2. /proc/self/smaps tracking (estimation-based)

• Capture /proc/[pid]/smaps before and after code execution
• Compare RSS (Resident Set Size) changes for file-backed mappings
• Pros: No root required, no external dependencies
• Cons: Estimates only (includes prefetching), affected by kernel page cache behavior

3. perf with page-fault events (system tool)

• Use perf stat -e page-faults or perf record -e page-faults
• Parse perf output to extract fault counts
• Multiply by page size (4KB) for byte estimate
• Pros: Standard Linux tool, reasonably accurate
• Cons: Requires perf installed, may need elevated privileges, estimates only

4. Hybrid approach (fallback strategy)

• Try strace first (current implementation)
• If bytes captured < file_size threshold (e.g., <50%), warn user about likely mmap usage
• Suggest alternative measurement or document limitation
• Pros: Works with current code, educates users
• Cons: Doesn't solve the measurement problem

Recommendation: Start with approach #4 (hybrid) as it requires minimal changes. Add a warning when captured I/O is suspiciously low relative to file size. For full mmap support, approach #2 (/proc/smaps) is most practical without new dependencies.

@copilot A couple of questions:

1. Can you give more detail about how the /proc/self/smaps approach works exactly
2. For the perf based approach, are the same syscalls that perf uses available in a python package? This might be an easier dependency to take, and give better error handling/ recovery.

Please just answer in a comment, don't write any code.

@copilot A couple of questions:

1. Can you give more detail about how the /proc/self/smaps approach works exactly
   ...

1) /proc/self/smaps detailed approach:

/proc/[pid]/smaps shows detailed memory mapping information. For tracking mmap'd file I/O:

Before execution:

• Read /proc/self/smaps (or /proc/[pid]/smaps for child)
• Parse each memory region, identify file-backed mappings (lines with pathname)
• Record baseline RSS (Resident Set Size) for each file mapping

After execution:

• Read /proc/self/smaps again
• Calculate RSS delta for file-backed regions
• Delta represents pages brought into RAM (accessed data)

Key fields in smaps:

Size: 1024 kB          # Total mapping size
Rss: 512 kB            # Currently in RAM
Referenced: 512 kB     # Recently accessed

Limitation: RSS includes prefetched pages and doesn't distinguish between first access vs. cached access, so it's an upper bound estimate.

2) Python packages for perf events:

Yes, perf_event syscalls are accessible via:

a) perf-event PyPI package - Direct wrapper around perf_event_open() syscall

• Lighter dependency than bcc-tools
• Still requires parsing output/events
• Lower-level API, more setup code needed

b) py-perf or similar - Higher-level wrappers

• Easier API but less common/maintained

However: Both still need privileges (CAP_PERFMON or relaxed perf_event_paranoid), similar to eBPF but without eBPF's full kernel access requirements. The main advantage over direct perf CLI is better error handling and programmatic control, but dependency management may be comparable to installing perf system package.